<!doctype html>
<html>
  <head>
    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-132775238-1"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());

      gtag('config', 'UA-132775238-1');
    </script>

    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, minimum-scale=1, initial-scale=1, user-scalable=yes">
    <link href="https://fonts.googleapis.com/css2?family=Nunito:wght@300;600&family=Open+Sans:wght@300;600&family=Roboto+Mono&display=swap" rel="stylesheet">
    <script type="text/javascript" src="./rapidoc-min.js"></script>
    <!-- Code Highlight -->
    <link rel="stylesheet" href="./prismjs/prism.css">
    <script src="./prismjs/prism.js"></script>

    <link rel="stylesheet" href="./index.css">
    <link rel="stylesheet" href="table.css">
    
  </head>
  <body style="background-color:#f9f9fb; color:494d55; margin:0 100px; padding:16px; font-family: Nunito;">
    <main>
      <h2>Introducing &lt;rapi-doc-mini&gt; Web Component </h2>
      <p> 
        <b>&lt;rapi-doc-mini&gt;</b> a new way to expose your API documentation. There are various styles and needs how one would like to document their APIs. 
        such as 
        <ul>
          <li>
            All the APIs are documented in one central place. This is where <b>&lt;rapi-doc&gt;</b> fits in. However for the rest of bullets listed below  <b>&lt;rapi-doc-mini&gt;</b> is your friend
          </li>
          <li>
           Expose just a few important APIs such as authentication etc as a part of a blog, to provide an initial understanding to your audience
          </li>
          <li>
            A step by step tutorial where in each step shows you a few APIs 
          </li>
          <li>
            Or you are explaining a business case which uses microservices, 
            where each microservice has its own APIs and the ask is to pick few APIs from each of theses microservice show how they work together in a single document
          </li>
        </ul>
      </p>

      <h2>Usage in a blog style writing</h2>
      <p style="flex:1">
        It is fairly common to write specifically about few APIs to provide an initial understanding to your users. 
        However in those cases you run the risk of your writeup getting outdated when the actual API changes its shape.
      </p>
      <p>
        <b>&lt;rapi-doc-mini&gt;</b> gives you this amazing capability to extract and expose any part of you Open-API spec including a built in API console to try out. 
        As an example shown below is how I am exposing a set of APIs in this writeup. 
        It is a very powerful and yet very easy to use tool that comes with many advantages, inluding syntax highlighting, built-in console, markdown support and many others. 
        <br/>
        <b>Below is the markup that you will put in your html </b>
        <br/>
        <pre class="shadow code-block" style="width:575px">
          <code class="language-html" style="border-radius:4px"> 
            &lt;rapi-doc-mini
              spec-url = "https://petstore.swagger.io/v2/swagger.json"
              style= "min-width:600px;"
              paths-expanded = "false"
              theme = "light"
              bg-color = "#f9f9fb"
            &gt; &lt;/rapi-doc-mini&gt;</code>
        </pre>
        Above HTML snippet will result in generating an API doc as shown below. Notice how it blends seamlessly with this writeup as if its a part of this page. 
        Go ahead and play with the below APIs, make live request and watch the responses, all from this very blog.
      </p>
      <rapi-doc-mini
        style= "min-width:600px;"
        spec-url="./specs/mock.yaml"
        theme = "light"
        paths-expanded = "false"
        bg-color = "#f9f9fb"
      > </rapi-doc-mini>
      <br/>
      <h3> Placement, Resize and Style</h3>
      If needed it can be resized to fit the layout needs. 
      Just like how you would use an &lt;img&gt; tag, in the same way you can use <b>&lt;rapi-doc-mini&gt;</b>
      and place and style per your needs.<br/>
      like shown below, I reduced its width, applied a thick border and attached some shadow 
      <br/><br/>
      <rapi-doc-mini
        style = "width:600px;border-radius: 4px; border: 2px solid #333; box-shadow: 0 3px 6px rgba(0,0,0,0.16), 0 3px 6px rgba(0,0,0,0.23);"
        spec-url="./specs/mock.yaml"
        theme = "light"
        schema-style = 'table'
        sort-endpoints-by = "method"
        layout = "column"
        paths-expanded = "false"
      > </rapi-doc-mini>
     
      <br/><br/>
      <h3>Pick only specific APIs from OpenAPI spec</h3>
      Instead of showing entire open-api spec you can just extract and choose to show what you need to show. This is done using <b>match-paths</b> attribute.
      <br/>Example below uses the same OpenAPI spec as we used above, but showing only the paths that we intend to

      <pre class="shadow1 code-block" style="width:575px">
        <code class="language-html">
          &lt;rapi-doc-mini
            style= "min-width:600px;border: 1px solid #eee; border-top-width:0"
            spec-url="../specs/mock.yaml"
            theme = "light"
            paths-expanded = "false"
            match-paths = "post /users"
          &gt; &lt;/rapi-doc-mini&gt;
        </code>
      </pre>
      <br/> 
      <rapi-doc-mini
        style= "min-width:600px; width:600px; border-radius:2px; border: 1px solid #eee; border-top-width:0"
        spec-url="./specs/mock.yaml"
        theme = "light"
        schema-style = 'table'
        sort-endpoints-by = "method"
        layout = "column"
        paths-expanded = "false"
        match-paths = "post /users"
      > </rapi-doc-mini>
    <br/>
    <h3>More complex RegEx based filtering of API is possible too (match-paths & match-type)</h3>
    Here we are using regular RegEx to select the paths which is either <span class="mono blue"> get /users/{userId}</span> &nbsp;&nbsp;or&nbsp;&nbsp; <span class="mono blue"> post /users</span>
    <pre class="shadow1 code-block" style="width:575px">
      <code class="language-html">
        &lt;rapi-doc-mini
          style= "min-width:600px;border: 1px solid #eee; border-top-width:0"
          spec-url="./specs/mock.yaml"
          theme = "light"
          paths-expanded = "false"
          match-paths = "^get /users/\{userId\}$|^post /users$"
          match-type = "regex"
        &gt; &lt;/rapi-doc-mini&gt;
      </code>
    </pre>

    <br/> 
    <rapi-doc-mini
      style= "min-width:600px; width:600px; border-radius:2px; border: 1px solid #eee; border-top-width:0"
      spec-url="./specs/mock.yaml"
      theme = "light"
      schema-style = 'table'
      sort-endpoints-by = "method"
      layout = "column"
      paths-expanded = "false"
      match-paths = "^get /users/\{userId\}$|^post /users$"
      match-type = "regex"
    > </rapi-doc-mini>

    <h3>Show it Minimzed or Expanded</h3>
    If expand/collapse is not your style, then have it always expanded and make it more natural and integrated part of your writeup.
    <br> Use the attribute <b>paths-expanded = "true"</b> to achive this <br/><br/>
    
    <rapi-doc-mini
      style= "min-width:600px; width:600px;"
      spec-url="./specs/mock.yaml"
      theme = "light"
      schema-style = 'table'
      sort-endpoints-by = "method"
      layout = "column"
      paths-expanded = "true"
      match-paths = "post /users"
      bg-color = "#f9f9fb"
    > </rapi-doc-mini>



  <h3>Include APIs from multiple specs</h3>
  <p>
    Pretty common with micro services, where you like to explain a business flow by consuming APIs from multiple services. 
    Each of these services may be having their own OpenAPI spec. 
    The ask is to pluk some APIs from different services and makeup a story. <br>
    Do not rewrite the API specific functionality again, make use of the existing OpenAPI spec and Use <b>&lt;rapi-doc-mini&gt;</b> to pluck and document APIs from differenct specs
  </p>
  <rapi-doc-mini
    style= "width:600px; border-radius: 4px; border: 1px solid #333"
    id = "thedoc" 
    spec-url="./specs/code-highlight.yaml"
    theme = "light"
    schema-style = 'table'
    sort-endpoints-by = "method"
    layout = "column"
    match-paths = "get /code"
  > </rapi-doc-mini>

  <h3>Use a different theme </h3>
  <rapi-doc-mini
    style= "width:600px; border-radius: 4px; box-shadow: 0 3px 6px rgba(0,0,0,0.16), 0 3px 6px rgba(0,0,0,0.23);"
    id = "thedoc" 
    spec-url="./specs/petstore.json"
    theme = "dark"
    schema-style = 'table'
    sort-endpoints-by = "method"
    layout = "column"
    match-paths = "/store"
  > </rapi-doc-mini>
  
  <h3>Handling non available specs</h3>
  <rapi-doc-mini
    style= "width:600px; border-radius: 4px; margin-bottom: 16px;"
    theme = "dark"
    id = "thedoc" 
    spec-url="./specs/fake-non-existing.json"
  > </rapi-doc-mini>
  <rapi-doc-mini
    style= "width:600px; border-radius: 4px; margin-bottom: 16px;"
    theme = "light"
    id = "thedoc" 
    spec-url="./specs/fake-non-existing.json"
  > </rapi-doc-mini>

</main>

  </body>
</html>
